home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / bbs / develop.zip / MSGS.DOC < prev    next >
Text File  |  1993-03-24  |  16KB  |  349 lines
  1.   WARNING:  This document is subject to change at any time.  Any changes made
  2.   will be indicated by a vertical bar (|) in column 1 of the file.
  3.  
  4. | Last update: 03/24/93
  5.  
  6. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  7.  
  8.   The following information documents the format for PCBoard's message base
  9.   and message index formats.
  10.  
  11.   The message base consists of 128-byte blocks of data.  A single 128 byte
  12.   header is placed at the start of each message base giving information such
  13.   as the number of messages in the message base and the low to high range of
  14.   message numbers within the message base.
  15.  
  16.   Each individual message subsequently consists of a 128-byte header
  17.   describing who the message is to and from and an indicator of how many
  18.   128-byte blocks comprise the entire message.
  19.  
  20.   The following layout is specified in a "byte offset" format such that the
  21.   first field begins at offset 0.
  22.  
  23.   The following is a definition of the variable types that will be used below:
  24.  
  25.     char   = a 1 byte character
  26.     str    = an array of 2 or more "char" bytes
  27.     bsreal = a 4 byte Basic Single Precision real number
  28. |   int    = a 2 byte integer
  29. |   long   = a 4 byte integer
  30. |   bitmap = a single byte with individual bits set on or off
  31.  
  32.   Note that strings are not NULL terminated and that the length specified for
  33.   the string is full number of useable and storeable bytes.  All strings are
  34.   padded with spaces to fill the entire field.
  35.  
  36.  
  37.   Message Base Header
  38.   -------------------
  39.  
  40.     Offset  Type   Length Description
  41.     ------ ------  ------ -----------
  42.        0   bsreal     4   High Message Number       (0 to 16,700,000)
  43.        4   bsreal     4   Low Message Number        (0 to 16,700,000)
  44.        8   bsreal     4   Number of Active Messages (0 to 32,767)
  45.       12   bsreal     4   Number of System Callers (Main Message Base Only)
  46.       16   str        6   The "LOCKED" field for pre-14.2 systems (see note 1)
  47.       22   str      106   Reserved for future use
  48.  
  49.  
  50.   Individual Message Headers
  51.   --------------------------
  52.  
  53.     Offset   Type   Length  Description
  54.     ------  ------  ------  -----------
  55.        0    char       1    Message Status Flag (see note 2)
  56.        1    bsreal     4    Message Number   (0 to 16,700,000)
  57.        5    bsreal     4    Reference Number (0 to 16,700,000)
  58.        9    char       1    Number of 128 Byte Blocks in Message (see note 3)
  59.       10    str        8    Date of Message Entry (in "mm-dd-yy" format)
  60.       18    str        5    Time of Message Entry (in "hh:mm" format)
  61.       23    str       25    Name of the User to whom the Message is Addressed
  62.       48    bsreal     4    Date of the Reply Message (in yymmdd format)
  63.       52    str        5    Time of the Reply Message (in "hh:mm" format)
  64.       57    char       1    The Letter "R" if the Message has a Reply
  65.       58    str       25    Name of the User who wrote the Message
  66.       83    str       25    Subject of the Message
  67.      108    str       12    Password Need to Read the Message (if any)
  68.      120    char       1    Active Status (225 = active, 226 = inactive)
  69.      121    char       1    The Letter "E" if the Message is to be Echoed
  70. |    122    str        4    Reserved for future use
  71. |    127    bitmap     1    Extended Header Flags
  72. |    128    char       1    Reserved for future use
  73.  
  74.  
  75. | Extended Header Format
  76. | ----------------------
  77. | A mesage may contain one or more EXTENDED HEADERS within the body of the
  78. | message.  Please refer to HEADERS.DOC for a discussion of each of these
  79. | headers and their uses.
  80. |
  81. | The following is the physical layout of the Extended Header within the
  82. | message body.  You may assume that as soon as the Extended Header ID is not
  83. | found that there are no more extended headers in the message body.
  84. |
  85. |   Offset   Type   Length  Description
  86. |   ------  ------  ------  -----------
  87. |      0    int        2    Extended Header ID = must be equal to 40FFh
  88. |      2    str        7    Extended Header Function
  89. |      9    char       1    A colon (:) character
  90. |     10    str       60    Extended Header Description (subj, to, from, etc)
  91. |     70    char       1    Status (N or R)
  92. |     71    char       1    Line Separator (E3h, or 0Dh for foreign systems)
  93. |
  94. | While any value may be used for the Extended Header Function field, the only
  95. | values recognized and processed directly by PCBoard v15.0 are:
  96. |
  97. |   "TO     "      TO Name (or address for internet)
  98. |   "FROM   "      FROM Name (or address for internet)
  99. |   "SUBJECT"      Subject of the message
  100. |   "ATTACH "      File Attachment
  101. |   "LIST   "      Carbon List TO Name
  102. |   "ROUTE  "      Routing information for netmail
  103. |   "ORIGIN "      Origin information for netmail
  104. |   "REQRR  "      Request Return Receipt
  105. |   "ACKRR  "      Acknowledgement Return Receipt
  106. |   "ACKNAME"      Acknowledgement (FROM) Name
  107. |   "PACKOUT"      Pack Out Date (date to remove message)
  108. |
  109. | The Carbon List header Description Field is further subdivided as follows:
  110. |
  111. |   Offset   Type   Length  Description
  112. |   ------  ------  ------  -----------
  113. |     10    str       50    Extended Header Description (subj, to, from, etc)
  114. |     60    str        6    Date Message Was Read
  115. |     66    str        4    Time Message Was Read
  116. |
  117. | The File Attach header Description Field is formatted as follows:
  118. |
  119. |     "FILENAME (SIZE) STOREDNAME"
  120. |
  121. | The entire field is padded out to 60 spaces just like the rest of the
  122. | extended headers.  The FILENAME is the name of the file that the caller
  123. | uploaded.  The SIZE is the size of the file.  The STOREDNAME is the name
  124. | under which the file is actually stored on disk.
  125.  
  126.  
  127.   Index File Format
  128.   -----------------
  129. | There are now two separate Index File Formats used by PCBoard.  There is an
  130. | older format which was used from the beginning, and a new v15.0 specific
  131. | format.
  132. |
  133. | We encourage all authors to upgrade to the v15.0 format.  However, in the
  134. | meantime, PCBoard is capable of working with BOTH formats.  PCBoard will
  135. | no longer USE the old style format, but it will keep it up to date for
  136. | those programs that need to access it.  This functionality can be disabled
  137. | if the system does not make use of any software that uses the old style
  138. | format and this can save both time and disk space.
  139. |
  140. | The two index filenames are the same root name as used for the message base
  141. | plus the addition of an extension as follows:
  142. |
  143. |        .NDX      for old-style index files
  144. |        .IDX      for v15.0 style index files
  145. |
  146. | Example:  MSGS.NDX and MSGS.IDX would be the two index files for MSGS.
  147. |
  148. | Version 15.0 Style Index
  149. | ------------------------
  150. | This new format has several changes and at the same time some operational
  151. | simularities that make it easy to implement.  These changes are:
  152. |
  153. | - The index record now has the offset stored as a long integer instead of as
  154. |   a single precision real number.
  155. |
  156. | - The offset is no longer the number of the message block but instead is the
  157. |   actual offset within the file.  (the old style offset had to be multiplied
  158. |   by 128 to arrive at a physical offset)
  159. |
  160. | - The index record now has the most commonly accessed information that is
  161. |   used by PCBoard to determine the accessability of a message - that is,
  162. |   to decide whether or not the message can be read by the caller.  By putting
  163. |   all of this information into the index PCBoard no longer has to read BOTH
  164. |   the index AND the message header to find out of the message is readable.
  165. |   This also greatly speeds up the Y-scan because for most scans it no longer
  166. |   has to read the message base but just the information in the index file can
  167. |   be used.
  168. |
  169. | - A date is now included in the index making it possible to quickly locate
  170. |   messages that are newer than a given date.
  171. |
  172. | - The index file is not PRE-formatted.  This means that sysops no longer
  173. |   have to worry about filling up the message base index or setting an
  174. |   appropriate "block size" for the index.  PCBoard and PCBPack simply
  175. |   maintain an index t